Amiga Tools 4

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Tools 4 / Amiga Tools 4.iso / tools / monitors / sysmon / sysmon.doc < prev

Wrap

Text File | 1996-02-26 | 24.9 KB | 553 lines

$VER: Sysmon.doc 0.2 (19.11.95) © 1995 by Etienne Vogt (Etienne.Vogt@obspm.fr) INTRODUCTION Sysmon is a system monitoring package based on a shared library and Shell based support commands. It requires AmigaOS 2.04 or higher. Main features are : - Precise CPU usage timing for all tasks with very low overhead. - System message logging daemon like UNIX syslogd (useful for debugging). - Safe System shutdown script (useful for BBS's and networked machines). This is a public *** BETA *** release, so it's not fully tested. In particular, I am not sure if it will work on a 68060 based machine. So if you are the lucky owner of a 68060 based amiga, please test this software and report the resulting behaviour back to me. My E-Mail address is listed in this file. Sysmon has been successfully tested on the following configurations : - A500 68000 ECS, 1 Mb Chip 1.5 Mb Slow 2 Mb Fast , OS 3.1 20 Mb IDE-XT + 170 Mb SCSI HDs - A3000 68030 ECS, 2 Mb Chip 8 Mb Fast , OS 3.1 100 Mb + 1 Gb SCSI HDs - A500 68040(PP&S) ECS , 1 Mb Chip 2 Mb Fast16 8 Mb Fast32 , OS 2.04 50 Mb SCSI HD - A4000 68040 AGA, 2 Mb Chip 8 Mb Fast , OS 3.0 250 Mb IDE + 1 Gb SCSI-2 HDs - A1200 68EC020/68882 AGA, 2 Mb Chip 5 Mb Fast , OS 3.0 60 Mb IDE + 100 Mb SCSI HDs This software is intended for experienced users. In particular, there are no GUI tools available yet; so if you are a mouse-maniac user that don't like typing Shell commands or editing ASCII configuration files, I'm afraid that this software is not for you. DISTRIBUTION Sysmon is Freely Distributable Copyrighted Software (FreeWare). It may be freely copied as long as it is kept intact. However, the support commands that do not require sysmon.library may be distributed separately. (see the OTHER COMMANDS section below). It may not be sold under any guise. I don't want others to make money out of my work. Distribution MUST BE FREE, except for media costs plus a token amount covering only shipping and handling. Authors of FreeWare may freely use the sysmon.library in their software. Authors of ShareWare may use the library at the cost of giving me a free registration (this includes upgrades as long as the software continues to use the library). Authors of commercial packages MUST obtain a written license agreement from me before selling software using the library. Fred Fish is explicitely allowed to include this package in his AmigaLibDisk collection (either on floppy disk or on CD-ROM), as is the aminet group for their Aminet CD-ROM. Usage and Distribution of Sysmon and sysmon.library is STRICTLY FORBIDDEN to: - Anyone affiliated with the french society FRANCE-FESTIVAL-DISTRIBUTION (especially Serge Hammouche). - Anyone affiliated with MICROSOFT CORPORATION or its subsidiaries. DISCLAIMER This software is provided "as is" without any warranty, either expressed or implied. By using this software, you accept the entire risk as to its quality and performance. Especially, as this software patches some private system functions, it can not be guaranteed that it will continue to work with future operating system versions, and it will certainly not work as is on a PowerPC based Amiga. CONTACTING THE AUTHOR I can be reached by E-Mail at the following address : Etienne.Vogt@obspm.fr Bug reports must include the complete hardware and software configuration, including any third party software that was running in the background. If you have any question or suggestion about this software, feel free to send me E-Mail. ARCHIVE CONTENTS Original Packed Ratio Date Time Name -------- ------- ----- --------- -------- ------------- 1568 942 39.9% 20-Nov-95 19:51:10 Sysmon/c/Freeze 672 495 26.3% 20-Nov-95 19:55:40 Sysmon/c/Halt 784 581 25.8% 20-Nov-95 19:53:38 Sysmon/c/Request 1436 1005 30.0% 20-Nov-95 19:49:22 Sysmon/c/RunBackground 6520 4238 35.0% 04-Nov-95 17:07:08 Sysmon/c/ShowSys 3504 2117 39.5% 20-Nov-95 19:47:32 Sysmon/c/StartSM 772 560 27.4% 20-Nov-95 19:57:14 Sysmon/c/SysLog 20208 11718 42.0% 05-Nov-95 16:22:34 Sysmon/c/sysmon 9192 5922 35.5% 19-Nov-95 00:57:22 Sysmon/c/Timer 1580 944 40.2% 20-Nov-95 19:58:38 Sysmon/c/UnFreeze 1900 1353 28.7% 20-Nov-95 20:00:08 Sysmon/c/UnMount 808 573 29.0% 20-Nov-95 20:01:26 Sysmon/c/ValidateWait 11629 3598 69.0% 05-Nov-95 17:04:02 Sysmon/docs/sysmon_lib.doc 6137 2419 60.5% 19-Nov-95 20:05:42 Sysmon/include/sysmon.h 5853 2409 58.8% 19-Nov-95 22:28:06 Sysmon/include/sysmon.i 826 237 71.3% 08-Oct-95 18:07:22 Sysmon/include/sysmon_pragmas.h 732 377 48.4% 08-Oct-95 18:05:56 Sysmon/include/sysmon_protos.h 5156 3270 36.5% 04-Nov-95 16:15:46 Sysmon/libs/sysmon.library 937 521 44.3% 02-Nov-95 00:14:08 Sysmon/s/Shutdown 241 194 19.5% 19-Nov-95 15:01:40 Sysmon/s/Sysmon.config 2787 1155 58.5% 20-Nov-95 19:48:32 Sysmon/src/Freeze.c 2310 1027 55.5% 20-Nov-95 19:49:24 Sysmon/src/Halt.c 2519 1164 53.7% 20-Nov-95 19:49:58 Sysmon/src/Request.c 3150 1338 57.5% 20-Nov-95 19:47:04 Sysmon/src/RunBackground.c 10922 3483 68.1% 04-Nov-95 17:03:56 Sysmon/src/ShowSys.c 7638 2785 63.5% 20-Nov-95 19:45:38 Sysmon/src/StartSM.c 2673 1122 58.0% 20-Nov-95 19:50:40 Sysmon/src/SysLog.c 4829 1690 65.0% 19-Nov-95 00:56:12 Sysmon/src/Timer.c 2809 1153 58.9% 20-Nov-95 19:52:18 Sysmon/src/UnFreeze.c 6700 2332 65.1% 20-Nov-95 19:52:50 Sysmon/src/UnMount.c 2740 1204 56.0% 20-Nov-95 19:53:10 Sysmon/src/ValidateWait.c 25481 9847 61.3% 21-Nov-95 10:50:08 Sysmon/sysmon.doc -------- ------- ----- --------- -------- 155013 71773 53.6% 21-Nov-95 10:51:00 32 files INSTALLATION - Copy the file 'libs/sysmon.library' to your LIBS: directory. - Copy the support commands in the 'c/' sub-directory to C: . - Copy the files in the 's/' sub-directory to S: . - You may also copy the files in the 'docs/' and 'include/' subdirectories wherever you like. - Load S:Startup-Sequence in your favorite editor. Locate the line with 'SetPatch' in it. Add a line just after it saying 'C:StartSM'. Save the modified Startup-Sequence. - Wait for disk activity to finish, then reboot your Amiga. Sysmon will then be started with the default configuration. - After bootup, open a shell and type 'showsys'. You should then get a listing of all tasks in the system, like this : AmigaOS 40.63 05-Nov-95 19:34:37 UpTime : 0 04:45:06 Address Name State Pri CPU [68000] Type 0020F700 DH0 WAIT 10 0 00:00:20.761 Process 0029E200 Workbench (Workbench) WAIT 1 0 00:01:38.599 Cli 4 0021B918 DH2 WAIT 10 0 00:00:37.442 Process 002A7628 Active WAIT 21 0 00:00:31.385 Process 00267930 « ConClip » WAIT 0 0 00:00:00.002 Process 00217138 SH0 WAIT 10 0 00:00:02.803 Process 00223A3C trackdisk.device WAIT 5 0 00:00:25.848 Task 0020703A input.device WAIT 20 0 00:22:01.744 Task 002B9C40 Clock WAIT 0 0 00:04:03.565 Process 00254248 « IPrefs » WAIT 0 0 00:00:03.761 Process 002AFE50 Spliner WAIT 0 0 00:00:03.037 Process 0022C758 ramlib WAIT 0 0 00:00:00.762 Process 00228458 DH3 WAIT 10 0 00:00:02.828 Process 0020B858 scsi.device WAIT 11 0 00:00:15.128 Task 00214C70 DF0 WAIT 10 0 00:00:04.401 Process 00221570 DF1 WAIT 10 0 00:00:03.449 Process 00246570 ErrorLog.daemon (ErrorLogD) WAIT 6 0 00:00:23.148 Cli 0 0026A978 RexxMaster WAIT 4 0 00:00:00.399 Cli 0 00297E78 CON WAIT 5 0 00:02:08.857 Process 002B1D78 ClickToFront WAIT 21 0 00:00:00.194 Process 0020DA8C trackdisk.device WAIT 5 0 00:00:35.705 Task 00241A88 VD0 WAIT 10 0 00:00:35.972 Process 0020C490 A590 SCSI handler WAIT 12 0 00:00:24.504 Task 002B5890 AppMenuCx WAIT 0 0 00:00:00.198 Process 00285C98 Background CLI (Snap) WAIT 1 0 00:00:13.573 Cli 2 0023A4A0 RAM WAIT 10 0 00:00:02.588 Process 002A49A0 AmigaEyes READY -1 0 00:10:44.476 Process 00223CB0 DH1 WAIT 10 0 00:00:07.265 Process 00296AD0 AmigaShell_3 (showsys) RUN 0 0 00:06:02.147 Cli 3 002339D8 Sysmon.server WAIT 3 0 00:00:00.106 Process 0020B2F8 console.device WAIT 5 0 00:00:00.400 Task CONFIGURATION The configuration file is used to set up various parameters of operations. It is usually located in the S: directory. If you want to put it somewhere else, you have to add the complete path to the file as argument to the StartSM command in the Startup-Sequence. The configuration parameters currently available are : - LOGFILE : This parameters sets up the name of the file used for the system message logging facility. Currently all messages go into a single file. You should place this file on a hard disk partition with sufficent free space available. The default file name is S:Sysmon.log - LOGWINDOW : This sets up the window specifications for syslog messages that are serious enough to be displayed in a window. You can also redirect them somewhere else like an AUX: serial terminal or even a file, but you must be aware that this 'file' is not closed after each message like the log file is. The default window specification is CON:20/50/600/80/SysLog/AUTO/CLOSE/WAIT - FILEPRI : Sets up the higher priority level of messages that will be logged in the log file; low values mean high severity like in UNIX (See the sysmon.h include file for the definitions). The default value is 7 (LOG_DEBUG) which means that all messages will be logged. - WINPRI : This is the same as the previous parameter but for the window logging. The default value is 4 (LOG_WARN), meaning that messages of class warning or more severe will be logged. - CONPRI : Sets up the higher priority level for logging to a serial port terminal (console). The logging is done via the smKPrintf() function which is not system friendly (accesses the serial port hardware directly). If you have something else than a terminal attached to your serial port (ex. a modem), you should leave this parameter to its default value of 0 (LOG_EMERG). This means that only system panic messages will be logged; these can not be disabled but are not currently used by the sysmon package (and should never be used by application or user programs). - LOGBUFFERS : This sets up the number of preallocated buffers to store syslog messages before they can be logged to disk and/or window by the Sysmon.server process. If you have a program that generates lots of messages and you think you are losing some of them, you should increase the number of buffers. The default value is 5. - STAMPPERIOD : Sets the time period in minutes between time stamping messages written to the logfile at priority level 6 (LOG_INFO). You can disable these messages by specifying a stamp period or 0. Default value is 60 minutes (one message every hour). - IDLELED : This enables you to monitor the CPU activity using the power LED. If IDLELED is set to YES, the system will dim the power LED when the CPU is idle and brighten it when a task is running. This can however cause interferences with audio output as the power LED also controls the low pass audio filter. Default value is NO. SUPPORT COMMANDS These support commands should be installed in your C: directory. They can only be used from the Shell. - StartSM: This command loads and initializes the sysmon.library and starts the Sysmon.server syslog process. It should be called from your Startup-Sequence right after the SetPatch command. Usage : StartSM CONF=CONFIGFILE CONFIGFILE : Specifies the path to the configuration file described before. It defaults to S:Sysmon.config - ShowSys: This command will give a list of all the tasks in the system with their address, name, state, priority, cumulated CPU usage and type. An example of the display generated by this command was given in the INSTALLATION section. Usage : ShowSys FULL/S FULL: This switch causes the command to also display the allocated stack size, signals usage, task flags and total dispatch count for each task. - Timer: This command runs another command as a subprocess and times the command execution. It then reports the elapsed time and the CPU time used by the command. It is similar to the UNIX 'time' command. Usage : Timer COMMAND/F/A COMMAND : The command that will be executed and timed. - Freeze: This command will suspend a given task by putting it in the FROZEN state. It uses the sysmon.library function smFreeze(). (see sysmon_lib.doc for further details). This can be useful to stop a looping task that is eating away all the CPU time available. Be careful though to not freeze system tasks or the whole machine may hang. The frozen task can be resurrected by the UnFreeze command. Usage : Freeze TASK,ADDR=ADDRESS/K TASK: The name of the task to be frozen. If it is not unique, the first task found in the system lists will be frozen. ADDRESS: You can alternatively to the name, specify the hexadecimal address of the task as displayed by ShowSys. - UnFreeze: This command will bring a previously frozen task back to life. Is uses the sysmon.library function smUnFreeze(). (see sysmon_lib.doc for further details). Usage : UnFreeze TASK,ADDR=ADDRESS/K TASK: The name of the task to be unfrozen. If it is not unique, the first task found in the frozen list will be unfrozen. ADDRESS: You can alternatively to the name, specify the hexadecimal address of the task as displayed by ShowSys. - Halt: This command will halt the system by displaying a guru-like deadend alert. It uses the sysmon.library function smHalt(). (see sysmon_lib.doc for further details). It is used by the shutdown script and is not intended to be called directly. Usage : Halt REBOOT/S,REKICK/S REBOOT : This switch bypasses the alert display and causes the system to reboot immediately. REKICK : This switch forces MMU-softkicked machines like the early A3000s to reload the kickstart file when rebooting. - SysLog: This command can be used to generate syslog messages from the Shell. Usage : MESSAGE/A,LEVEL/K/N,NOHEAD/S,NOWIN/S,NOFILE/S MESSAGE : The message text body which must be inserted between double quotes if it contains spaces. The message length is limited to SM_MAXLOGCHARS bytes (currently 256). LEVEL : The priority level of the message in numeric form (see sysmon.h) Do not use the LOG_EMERG (0) and LOG_ALERT (1) values without good reasons. NOHEAD : This switch suppresses the header that is normally prepended to each message. This allows you to split a single long message in smaller parts. NOWIN : Do not log this message to the log window regardless of priority settings. NOFILE : Do not log this message to the log file regardless of priority settings. OTHER COMMANDS These commands do not depend on sysmon.library and thus are not to be considered part of the sysmon package, so they can be distributed separately. I wrote them for my own usage and decided to distribute them with sysmon because they may be useful to the Amiga community. The UnMount command is also used by the shutdown script. - RunBackground: This command starts a command as a detached process. Unlike the standard 'run' command, it automatically redirects the standard input and output to NIL: so the shell can be closed and it also allows you to specify options such as the new process priority and stack size. Usage : STACK=STACKSIZE/K/N,PRI=PRIORITY/K/N,DELAY/K/N,NOREQ/S,COMMAND/F/A STACKSIZE : The size of the stack to allocate for the new process. Defaults to the current shell stack size. PRIORITY : The priority to give to the new process. Defaults to the current process priority. DELAY : Optional delay after the new process startup and before the command returns. This can be used to avoid concurrent accesses to a disk. NOREQ : This switch will disable DOS requesters for the newly created process. Unfortunately, software error requesters are also disabled, so a CPU trap will cause an immediate guru reboot. COMMAND : The command to be executed. - UnMount: This command will try to unmount a DOS device by sending it an ACTION_DIE packet and optionally an ACTION_INHIBIT packet if the ACTION_DIE fails. It is used by the shutdown script to stop filesystem accesses before halting the system. Note that very few filesystems or handlers currently implement the ACTION_DIE packet (An exception is the CrossDosFileSystem). Usage : DEVICE,INHIBIT/S,RETRY/K/N,ALL/S,FREENODE/S DEVICE : The name of the DOS device to unmount. INHIBIT : This switch causes the command to send an ACTION_INHIBIT packet if the ACTION_DIE fails. ACTION_INHIBIT causes the filesystem to appear as 'BUSY' on the workbench screen, like during a format or diskcopy. RETRY : The number of retries for the ACTION_INHIBIT if the first one is rejected because the filesystem is busy. The retry period is 1 second and the default number of retries is 10. ALL : Finds all mounted filesystems and tries to unmount them (except the RAM-handler). Used by shutdown script. FREENODE: This switch causes the command to remove and free the device node after the handler has been stopped. Things attached to the device node like a file system startup message are not freed. It is similar to an 'Assign device: DISMOUNT' command. - Request: This command enables/disables system requesters in the current shell. This can be useful for remote shells or in the User-Startup if you make assigns to external disks that may not be always connected. Usage : OFF/S,ON/S,WB/S OFF : Disables system requesters in the current shell. Unfortunately, software failure requesters are also disabled causing an immediate guru reboot in the event of a CPU trap. ON : Enables system requesters on the current screen. For a remote shell, enables system requesters on the default public screen. WB : Enables system requesters on the default public screen, usually the Workbench screen. This is the default setting at startup. - ValidateWait: This command waits until the specified volume is validated. If it does not become validated within a specified period, it will time out and return an error condition to the Shell. It may be a good idea to put a 'ValidateWait SYS:' command at the beginning of your Startup-Sequence. Usage : DRIVE/A,TIMEOUT/K/N DEVICE : The device (or assign) to check for validation. TIMEOUT: The amount of time in seconds before timing-out. Defaults to 300 seconds (5 minutes). THE SHUTDOWN SCRIPT The shutdown script should be placed in your S: directory. It enables you to perform a safe power down of your system. This is particularly useful if your machine is connected to a network or runs a BBS. You should not edit this script as it may change in a future version of the Sysmon package. Instead, you should create a User-Shutdown script in S: where you can put commands to customize the shutdown sequence. The sequence of events performed by this script is as follows : - First ask the user for confirmation, unless the NOCONF switch was specified on the command line. If you enter 'y', the shutdown continues, else it is aborted. - Set the shell priority to 2, and send a syslog message at level 4 (LOG_WARN). - Execute the S:User-Shutdown script if it exists. You can put commands in this script to stop commodities or network protocol stacks for example. You can also create a Final-Shutdown script in RAM: (via echo or copy commands) that will be executed later. All commands used in Final-Shutdown must be copied to RAM: - Copy all further needed commands to RAM:, reset the search path to RAM: - Find and unmount all filesystems except RAM:, using UnMount ALL INHIBIT. - Execute the RAM:Final-Shutdown script if created by User-Shutdown. - Halt the system via the Halt command. If the REBOOT and/or REKICK options were given on the command line, they are passed to the Halt command. The REBOOT option will cause the system to reboot immediately. If it is not specified, the Halt command will stop all running tasks and display a guru like deadend alert saying 'System Shutdown Complete'. You can then safely turn the power off or reboot by pressing the left mouse button. Usage : Shutdown REBOOT/S,REKICK/S,NOCONF/S REBOOT : This switch is passed to the 'Halt' command at the end of the script. It bypasses the alert display and causes the system to reboot. REKICK : This will force MMU-Softkicked machines like early A3000s to reload the kickstart file when rebooting. NOCONF : Skip the confirmation question. THE SYSMON MONITOR The sysmon monitor is an interactive shell based program that allows you to display the system lists and variables and interact with them (not implemented yet). This program is still under development and more commands will be implemented in future releases. When you type 'sysmon' on the command line, you will get the 'SYSMON>' prompt back that tells you that the monitor is waiting for commands. You can then type sysmon commands (not to be confused with the shell-based sysmon support commands) or exit with the 'EXIT' or 'QUIT' commands. You can also specify a command directly on the command line. In this case, Sysmon will execute the command and exit immediately thereafter. All sysmon commands can be abreviated to the minimum number of characters required to uniquely identify the command. For example, you can type 'sh lib' instead of 'show libraries'. Currently implemented commands are : - EXIT: - QUIT: These commands will exit the sysmon monitor. An end of file (CTRL-\) at the 'SYSMON>' prompt will do the same. - SHOW: This command is used to display system lists and variables. The item to display is given as first argument to the SHOW command. · SHOW TASKS will display all the tasks in the system, in a manner similar to the 'ShowSys' support command. · SHOW LIBRARIES will display all shared libraries loaded in the system with version number, open count, negative and positive sizes of the library node and node priority. · SHOW DEVICES displays all loaded exec devices · SHOW RESOURCES displays the exec Resource list. · SHOW RESIDENTS displays the resident module array. · SHOW PORTS displays the public Message Port list. · SHOW SEMAPHORES displays the public Signal Semaphore list. · SHOW MEMORY displays the Memory Header list. · SHOW INTERRUPTS displays the Interrupt Nodes installed. · SHOW FONTS displays the Text Fonts loaded in memory. · SHOW MEMHANDLERS displays the Low Memory Handler list on Amiga OS 3.0+. · SHOW LOAD periodically displays the top CPU eating processes and total CPU load. The list is updated every 5 seconds and includes upto 16 processes. A process which takes less than 1 millisecond in an update cycle is not displayed; also processes which start and exit within a single cycle can not be taken into account. Type CTRL-C to exit from this command. An example display from a 'quiet' 68000 system is showed below : UpTime : 0 03:52:16 Update : 00:00:05.010 CPU Load : 18.6 % Address Name Load CPUTime 00296BB0 AmigaShell_3 (sysmon) 6.9 % 00:00:00.344 0020703A input.device 4.5 % 00:00:00.226 00297F58 CON 3.1 % 00:00:00.155 002A4A30 AmigaEyes 1.8 % 00:00:00.090 002B9AC8 Clock 1.5 % 00:00:00.077 0029E290 Workbench (Workbench) 0.5 % 00:00:00.025 00224FE4 trackdisk.device 0.0 % 00:00:00.003 0020F004 trackdisk.device 0.0 % 00:00:00.001 WRITING PROGRAMS FOR SYSMON You can use the sysmon.library in your own programs. See the DISTRIBUTION section for legal details. The library contains public functions that can be used to monitor cpu usage, send syslog messages to the Sysmon.server process, etc... Read the sysmon_lib.doc autodoc file and the sysmon.h include file for further information. Sources for the support commands are provided as examples.